혼자 공부하는 바이브 코딩 — 7장 클로드 코드 AI 에이전트로 개발팀 구성하기 딥다이브 학습 노트

출처: 혼자 공부하는 바이브 코딩 with 클로드 코드 (조태호) | 참고: https://github.com/taehojo/vibecoding

7장에서 다루는 내용

• AI 서브에이전트의 개념과 생성 — 코드 리뷰어, 최적화, UX 디자인 에이전트 만들기
• 서브에이전트 간 협업 — 여러 에이전트가 병렬/직렬로 프로젝트 개선
• AI 개발팀 구축 — 5가지 역할(제품 기획, 백엔드, 프론트엔드, 품질 보증, AI 통합)로 실전 앱 자동 제작

전체 흐름도

[07-1 AI 에이전트 이해하기]              [07-2 소프트웨어 개발 자동화하기]
    |                                      |
    v                                      v
+---------------------------+   +-----------------------------------+
| 에이전트 = AI 대리인       |   | 나만의 AI 개발팀 구축              |
| 서브에이전트 = 전문화된 AI  |   | 5개 역할 에이전트 생성             |
|                           |   | - 제품 기획 관리자                |
| /agents 명령어로 생성      |   | - 백엔드 개발자                   |
| - 코드 리뷰어 (Read-only)  |   | - 프론트엔드 개발자               |
| - 최적화 (All tools)      |   | - 품질 보증 엔지니어               |
| - UX 디자이너 (All tools)  |   | - AI 통합 전문가                  |
|                           |   |                                   |
| 서브에이전트 간 협업 테스트  |   | 실전 앱 1: AI 공감 다이어리        |
| 직렬/병렬 처리 방식        |   | 실전 앱 2: PDF 요약 AI             |
+---------------------------+   +-----------------------------------+

선수 지식 체크리스트

• [ ] 5장: 커스텀 명령어, 명령어 체이닝
• [ ] 4장: 단계별 프롬프트, 세션 관리
• [ ] 6장: API 연동 기본 개념

핵심 키워드

07-1 클로드 코드의 AI 에이전트 이해하기

한 줄 요약

클로드 코드의 /agents 명령어로 코드 리뷰어, 최적화, UX 디자인 등 전문 서브에이전트를 생성하고, 이들이 협업하여 프로젝트를 개선하는 과정을 실습한다.

에이전트란?

에이전트(Agent) = 영어로 '대리인', 즉 대신 일하는 사람

개발자가 '무엇을 달성할지'를 지정하면,
에이전트가 '어떻게 할지'를 스스로 결정하여 작업을 수행한다.

혼자 진행하는 프로젝트에서:
코드 작성 -> 디자인 -> 테스트 -> 버그 수정 (반복되는 작업)
-> 서브에이전트로 역할 분담하면 효율적!

서브에이전트 vs 커스텀 명령어

코드 리뷰어 에이전트 생성 (실습)

Step 01: '/agents' 명령어 입력 -> 서브에이전트 인터페이스 열기
Step 02: 'Create new agent' 선택
Step 03: 적용 범위 선택 -> '1. Project (.claude/agents/)'
         (프로젝트 수준: 현재 프로젝트에서만 활동)
Step 04: 생성 방법 -> '1. Generate with Claude' (자동 생성)
Step 05: 에이전트 설명 입력:
         "코드 리뷰어: 코드를 읽고 버그가 없는지, 코딩 규칙에 따라
          올바르게 작성되었는지를 점검하고 성능 최적화를 제안하는
          전문 코드 품질 검토자"
Step 06: 도구 권한 -> 'Read-only tools' (코드 검토만, 수정은 안 함)
Step 07: AI 모델 -> 'Opus' (복잡한 추론에 강력)
Step 08: 배경색 -> 'Blue'
Step 09: 확인 후 저장 -> .claude/agents/code-bug-analyzer.md 생성됨

AI 모델 선택 가이드

비용이 걱정되면 Sonnet으로 시작하고, 복잡한 분석이 필요한 에이전트만 Opus로 설정하는 것이 효율적이다.

서브에이전트 사용하기

프롬프트:
> code-bug-analyzer에게 '냉장고를 부탁해' 애플리케이션 코드를
  검토하게 해 줘.

-> 잠시 기다리면 코드 리뷰 결과가 출력됨
-> 상세한 버그 리포트와 함께 개선 사항이 체계적으로 정리됨

TIP: 에이전트 이름이 길면 Tab 키로 자동완성 사용 가능
     여러 에이전트를 동시에 호출하려면 쉼표(,)로 구분

최적화 에이전트 생성

프롬프트: "최적화 전문가: 애플리케이션의 작동을 원활하게 개선하고,
          속도를 빠르게 만들며, 병목 지점을 찾아서 해결하는
          시스템 성능 최적화 엔지니어"

설정:
- 도구 권한: All tools (코드를 직접 수정해야 하므로)
- AI 모델: Inherit from parent (메인과 같은 모델)
- 배경색: Green
-> 생성된 에이전트: 'performance-optimizer'

UX 디자인 에이전트 생성

프롬프트: "UX 디자이너: 사용자가 쉽고 편하게 이용할 수 있도록
          화면 디자인, 버튼 배치, 에러 메시지를 개선하는
          사용자 경험 전문가"

설정:
- 도구 권한: All tools
- AI 모델: Inherit from parent
- 배경색: Orange
-> 생성된 에이전트: 'ux-design-advisor'

서브에이전트 간 협업 테스트

프롬프트:
"code-bug-analyzer로 '냉장고를 부탁해' 애플리케이션 코드 전체를 리뷰한 뒤,
 발견한 문제를 performance-optimizer가 수정해서 성능 최적화한 다음,
 ux-design-advisor가 사용자 경험을 개선하게 해 줘."

-> 클로드 코드가 세 서브에이전트를 동시에 활성화해 작업 수행
-> 코드 리뷰어: 버그와 개선점 찾기
-> 최적화 에이전트: 속도 개선
-> UX 디자인 에이전트: 인터페이스 개선

직렬 처리 vs 병렬 처리

직렬 처리 (serial processing):
에이전트 A 완료 -> 에이전트 B 시작 -> 에이전트 C 시작
장점: 안정적, 일관성 높음 (선행 작업 결과를 다음이 참조)
단점: 시간이 오래 걸림

병렬 처리 (parallel processing):
에이전트 A -------> 완료
에이전트 B -------> 완료   (동시 실행)
에이전트 C -------> 완료
장점: 빠른 속도 (각자 독립적인 영역 담당)
단점: 파일 충돌 가능성 있음

클로드 코드가 작업의 성격과 파일 충돌 가능성을 고려해
자동으로 직렬/병렬 중 하나를 택한다.

작업 결과 백업하기

여러 에이전트가 동시에 작업하면 예상치 못한 충돌/중복 수정 발생 가능

프롬프트: "현재 상태를 백업해 줘."
-> 클로드 코드가 backup 디렉터리 생성 후 모든 파일 복사

문제 발생 시:
프롬프트: "백업으로 복원해 줘."
-> 이전 상태로 되돌림

핵심 체크포인트

• 에이전트 = 스스로 판단하여 작업 수행하는 AI 대리인
• /agents 명령어로 전문 서브에이전트를 생성/관리
• 도구 권한(Read-only/All tools)과 AI 모델을 역할에 맞게 설정
• 여러 서브에이전트가 직렬/병렬로 협업하여 프로젝트를 종합 개선
• 작업 전 백업으로 안전장치 확보

07-2 AI 에이전트로 소프트웨어 개발 자동화하기

한 줄 요약

실제 개발팀의 구조를 본떠 5개의 전문 서브에이전트(제품 기획/백엔드/프론트엔드/품질 보증/AI 통합)를 구성하고, 'AI 공감 다이어리'와 'PDF 요약 AI' 앱을 자동으로 만든다.

소프트웨어 개발팀의 구성과 역할

+--------------+  +--------------+  +--------------+
|  제품 기획    |  |  백엔드      |  | 프론트엔드   |
|  관리자(PM)   |  |  개발자      |  | 개발자       |
|              |  |              |  |              |
| PRD 작성     |  | 서버/DB 설계 |  | 화면/UI 구현 |
| 기능 정의    |  | API 연동     |  | 반응형 디자인 |
| 일정 관리    |  | 핵심 로직    |  | 사용자 경험  |
+------+-------+  +------+-------+  +------+-------+
       |                 |                 |
       +----------+------+                 |
                  |                        |
       +----------+------------------------+
       |
+------+-------+  +--------------+
|  품질 보증    |  |  AI 통합     |
|  엔지니어(QA) |  |  전문가      |
|              |  |              |
| 기능 테스트  |  | LLM 연동    |
| 버그 수정    |  | 프롬프트 최적화|
| 안정성 확보  |  | 모델 파인튜닝 |
+--------------+  +--------------+

서브에이전트 5개 생성

모든 에이전트의 공통 설정: - 적용 범위: 1. Project (.claude/agents/) - 생성 방법: 1. Generate with Claude - 도구 권한: All tools - AI 모델: 1. Sonnet (기본)

실전 앱 1: AI 공감 다이어리

5W1H 프레임워크로 요구사항 정리

What: AI 공감 다이어리 — 사용자가 오늘 있었던 일을 한 줄로 쓰면
      AI가 감정을 분석하고 공감과 위로를 해주는 일기 앱

Why:  사용자의 하루를 기록하고 정서적 지원을 제공하여
      마음의 안정을 돕기 위함

When: 지금 바로 개발 시작하여 즉시 사용 가능한 완성품 제작

Where: 웹 브라우저에서 실행, 사용자의 로컬 환경에서 작동

How:
  - OpenRouter API와 DeepSeek V3.1 무료 모델을 활용
  - 감정 분석 및 공감 메시지 생성
  - 따뜻하고 편안한 느낌의 UI 디자인 적용
  - API 키는 현재 프로젝트 폴더의 '.env' 파일에서 읽어와 사용
  - 최종 결과물은 'index.html' 단일 파일로 제작
  - 철저한 테스트를 통해 안정적인 버전 완성

Who:
  - 백엔드 개발자: API 연동, 감정 분석과 공감 메시지를 생성하는 기능 구현
  - 프론트엔드 개발자: 따뜻하고 편안한 느낌의 일기장 UI 제작
  - 품질 보증 엔지니어: 여러 상황을 테스트하고 문제 발견 시 완전히 해결될 때까지 수정

개발 프롬프트

프롬프트:
"AI 공감 다이어리를 만들어 줘. 오늘 있었던 일을 한 줄로 쓰면, AI가
 감정을 분석하고 공감하며 위로해 주는 일기 애플리케이션이야.
 backend-architect가 OpenRouter API를 연동해서 감정 분석과 공감
 메시지를 생성하는 기능을 구현해 줘. DeepSeek V3.1 무료 모델을
 사용하고, API 키는 현재 폴더의 '.env' 파일에 저장된 것을 사용해.
 frontend-developer가 따뜻하고 편안한 느낌의 일기장 UI를 만든 다음,
 qa-engineer가 실제로 여러 상황에서 문제없이 작동하는지 테스트해 줘.
 문제를 발견하면 완전히 해결될 때까지 수정하고, 최종 버전을
 브라우저에서 바로 쓸 수 있는 'index.html' 파일로 만들어 줘."

동작 결과

에이전트들이 순차적으로 작업:
1. backend-architect -> API 구현 (약 2분)
2. frontend-developer -> UI 구현 (약 3분)
3. qa-engineer -> 테스트 및 버그 수정 (약 5분)

완성된 AI 공감 다이어리 기능:
- 한 줄 일기 입력 -> 감정 분석하기 버튼
- 7가지 감정 분류 (기쁨, 슬픔, 분노, 두려움, 놀람, 평온, 혼재)
- 감정 강도 바 표시 (1~10)
- 공감 메시지 생성
- 일기 저장/삭제 기능
- 따뜻하고 편안한 UI, 반응형 디자인

실전 앱 2: PDF 요약 AI

역할 배분

개발 프롬프트

프롬프트:
"PDF 문서를 업로드하면 AI가 요약해주는 웹 애플리케이션을 만들 거야.
 먼저 product-manager-prd가 PDF 문서 요약 앱의 상세 PRD와 기능 명세를 작성하고,
 backend-architect가 PDF 파일 업로드, 텍스트 추출 기능을 구현해.
 ai-integration-specialist가 OpenRouter API를 연동해서 추출된 텍스트를 요약하는
 기능을 구현해 줘. DeepSeek V3.1 무료 모델을 사용하고, API 키는 현재 폴더의
 '.env' 파일에 저장된 것을 사용해.
 frontend-developer가 드래그&드롭 파일 업로드 UI와 요약 결과를 깔끔하게 표시하는
 한글 인터페이스를 구현한 다음,
 qa-engineer가 실제로 여러 상황에서 문제없이 작동하는지 테스트해 줘.
 문제를 발견하면 완전히 해결될 때까지 수정하고, 최종 버전을
 브라우저에서 바로 쓸 수 있는 'index_pdf.html' 파일로 만들어 줘."

완성된 PDF 요약 AI 기능

+--------------------------------------+
|      PDF 문서 요약 서비스              |
+--------------------------------------+
|                                      |
|  [PDF 파일을 여기에 드래그하세요]      |
|  (드래그&드롭 또는 파일 선택)          |
|                                      |
|  요약 모드 선택:                      |
|  ( ) 일반 요약  ( ) 간단 요약         |
|  ( ) 상세 요약                        |
|                                      |
|  [요약 생성하기]     [초기화]          |
|                                      |
|  요약 결과:                           |
|  ------------------------------------+
|  (AI가 생성한 요약 내용 표시)          |
|                                      |
|  핵심 포인트:                         |
|  1. ...                              |
|  2. ...                              |
|                                      |
|  [복사] [다운로드] [공유]             |
+--------------------------------------+

구현된 기능:
- 드래그&드롭 PDF 업로드 (50MB 제한)
- PDF.js를 통한 텍스트 추출
- OpenRouter API + DeepSeek V3.1 연동 (API 키 포함)
- 3가지 요약 모드 (간단/일반/상세)
- 완전한 한글 인터페이스
- 다크모드 지원
- 결과 복사/다운로드/공유
- 키보드 단축키 (Ctrl+U, Ctrl+Enter, Ctrl+R)
- 접근성 WCAG 2.1 AA 준수
- 반응형 디자인

에이전트 팀 운영 노하우

1. 프로젝트 성격에 따라 필요한 서브에이전트만 선택
   (5개 모두 사용할 필요 없음)

2. 에이전트 수가 많으면 맥락 관리, 리소스 분배 등 관리가 복잡해짐
   -> 적정 수를 유지하는 것이 중요

3. 프롬프트에 에이전트의 정확한 실제 이름을 사용
   -> '/agents' 명령으로 생성된 에이전트 목록 확인 가능

4. 문제가 발생하면 클로드 코드에게 구체적으로 입력하여 수정 요청

핵심 체크포인트

• 실제 개발팀 구조 그대로 5개 역할의 서브에이전트를 구성
• 5W1H 프레임워크로 제품 요구사항을 체계적으로 정리
• 에이전트들이 순차적/병렬로 협업하여 완성도 높은 앱 자동 생성
• AI 공감 다이어리: 감정 분석 + 공감 메시지 + 일기 저장
• PDF 요약 AI: 드래그&드롭 업로드 + AI 요약 + 다양한 출력 모드
• 프로젝트에 필요한 에이전트만 선택하여 효율적으로 운영

연습문제 풀이

Q1: 커스텀 명령어와 에이전트의 기술적 차이점으로 옳은 것을 고르세요.

A: (2) 에이전트는 독립적인 AI 모델을 선택할 수 있지만 커스텀 명령어는 메인 세션의 모델을 공유한다. 커스텀 명령어는 .md 파일로 저장되는 단축키이고, 에이전트는 독립적인 AI 전문가로서 모델/도구 권한/컨텍스트를 개별 설정할 수 있다.

Q2: 에이전트 생성 시 '4. Inherit from parent' 옵션을 선택했을 때의 동작으로 옳은 것을 고르세요.

A: (2) 메인 세션에서 사용 중인 모델을 그대로 상속받는다. 가장 저렴한 모델을 자동 선택하거나, 최신 모델로 자동 업그레이드하는 것이 아니라, 부모(메인 대화)가 사용하는 모델과 동일한 모델을 사용한다.

Q3: 에이전트에게 Read-only 권한만 부여했을 때 수행할 수 없는 작업은?

A: (3) 발견한 버그 수정, (4) 새로운 테스트 파일 생성. Read-only 에이전트는 코드 파일 읽기와 분석, 버그 리포트 생성은 가능하지만, 직접 코드를 수정하거나 새 파일을 만드는 것은 불가능하다.

Q4: QA 에이전트의 테스트 시간이 백엔드/프론트엔드보다 오래 걸리는 이유는?

A: (2) QA 에이전트는 이전 에이전트들의 작업 결과를 모두 검토해야 하기 때문이다. 여러 시나리오를 테스트하고, 발견한 오류를 수정하는 과정까지 포함하므로 자연스럽게 가장 오래 걸린다.

Q5: PDF 요약 앱에서 제품 기획 관리자가 생성한 PRD를 다른 에이전트들이 참조하는 방식으로 옳은 것은?

A: (1) PRD가 프로젝트 폴더에 생성되어 각 에이전트들이 접근한다. 에이전트들이 순차적 또는 병렬로 작업하며 PRD를 참조하게 된다. PRD는 .claude/agents/ 폴더가 아니라 프로젝트 폴더에 저장되어 모든 에이전트가 공유한다.

부록 A: 용어 사전

부록 B: 핵심 비교표

부록 C: 추천 참고 자료 & 링크